ASP.NET Universal Providers

Last update: 11 January 2012

The SqlMembershipProvider, SqlRoleProvider, SqlProfileProvider classes that shipped in ASP.NET through version 4 support only Microsoft SQL Server and Microsoft SQL Server Express. They do not support newer offerings such as Microsoft SQL Azure and Microsoft SQL Server Compact.

ASP.NET Universal Providers have been created in order to extend support to all editions of SQL Server 2005 and later and to SQL Azure. If you use these providers to develop your application, the application will be ready for cloud environments like Azure.

Other than supporting additional storage options, the providers work like the existing SQL-based providers. Except as noted below, using ASP.NET Universal Providers requires no change in any of your applications.

·         Installing and Configuring ASP.NET Universal Providers

·         Selecting a Data Store

·         Storing Data in Session State using ASP.NET Universal Providers

·         Known Issues

·         Additional Resources

·         Disclaimer

Installing and Configuring ASP.NET Universal Providers

To install ASP.NET Universal Providers, you use a NuGet package, which installs all required files (including this documentation). The NuGet package automatically enables the new providers when it is installed. By default, the NuGet package configures provider to use SQL Server Express. To use SQL Server Compact or SQL Azure, you must change the connection string for the provider, as explained later in this document.

To enable the providers, the NuGet package adds configuration entries in the web.config file. The configuration for these providers is the same as the existing SqlMembershipProvider class, but the type parameter is set to the type of the new providers, as shown in the following table:

SQL Provider Types	Equivalent Type for Universal Providers
System.Web.Security.SqlMembershipProvider	System.Web.Providers.DefaultMembershipProvider
System.Web.Profile.SqlProfileProvider	System.Web.Providers.DefaultProfileProvider
System.Web.Security.SqlRoleProvider	System.Web.Providers.DefaultRoleProvider
(Built into default provider)	System.Web.Providers.DefaultSessionStateProvider

In the web.config file, the configuration looks like the following example (the connection string has been wrapped for readability). The differences from the configuration for older SQL-based providers are highlighted. Notice that a section has been added to define custom session-state handling using a custom provider, as described later under Storing Data in Session State using ASP.NET Universal Providers.

<configuration>

<connectionStrings>

  <add name="DefaultConnection"

    connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=aspnetdb;Integrated Security=True"

    providerName="System.Data.SqlClient" />

  </connectionStrings>

  <system.web>

    <membership defaultProvider="DefaultMembershipProvider">

      <providers>

        <clear />

        <add name="DefaultMembershipProvider"

             type="System.Web.Providers.DefaultMembershipProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" 

             connectionStringName="DefaultConnection"

             enablePasswordRetrieval="false"

             enablePasswordReset="true"

             requiresQuestionAndAnswer="false"

             requiresUniqueEmail="false"

             maxInvalidPasswordAttempts="5"

             minRequiredPasswordLength="6"

             minRequiredNonalphanumericCharacters="0"

             passwordAttemptWindow="10"

             applicationName="/" />

      </providers>

    </membership>

    <profile defaultProvider="DefaultProfileProvider">

      <providers>

        <clear />

        <add name="DefaultProfileProvider"

             type="System.Web.Providers.DefaultProfileProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" 

             connectionStringName="DefaultConnection"

             applicationName="/" />

      </providers>

    </profile>

    <roleManager defaultProvider="DefaultRoleProvider" enabled="false">

      <providers>

        <clear />

        <add name="DefaultRoleProvider"

             type="System.Web.Providers.DefaultRoleProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"

             connectionStringName="DefaultConnection"

             applicationName="/" />

      </providers>

    </roleManager>

    <sessionState mode="Custom" customProvider="DefaultSessionProvider">

      <providers>

        <add name="DefaultSessionProvider"

           type="System.Web.Providers.DefaultSessionStateProvider, System.Web.Providers, Version=1.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"

           connectionStringName="DefaultConnection"

           applicationName="/" />

      </providers>

    </sessionState>

  </system.web>

Selecting a Data Store

By default, the NuGet package sets the connection string to use a SQL Server Express database (wrapped here for readability):

"Data Source=.\SQLEXPRESS;Initial Catalog=aspnetdb;Integrated Security=True" providerName="System.Data.SqlClient" 

If you want to use SQL Server Compact, change the connection string as shown in the following example:/o:p>

<connectionStrings>

  <add name="DefaultConnection" connectionString="Data Source=|DataDirectory|\aspnet.sdf" 

      providerName="System.Data.SqlServerCe.4.0"/>

</connectionStrings>

If you want to use SQL Azure, change the connection string as shown in the following example (wrapped for readability):

<connectionStrings>

  <add name="DefaultConnection" 

     connectionString="data source=myDNSName;

         User ID=myUserName;Password=myPassword;

         Encrypt=true;Trusted_Connection=false=false"

     providerName="System.Data.SqlClient"/>

<connectionStrings>

Storing Data in Session State using ASP.NET Universal Providers

By default, ASP.NET stores session data using an in-process (in-memory) session provider. This provider allows you to put any object in session state, because session state simply holds a reference to the object, not the object itself.

However, cloud environments might run your application on multiple computers. Therefore, for cloud-based applications, the application must store session state in some form of storage (like a database) that be accessed by more than one machine. This puts some restrictions on what data you store in session state — essentially, the data must be serializable.

When you install ASP.NET Universal Providers, the installation process configures session state to use the System.Web.Providers.DefaultSessionStateProvider type, as shown in the web.config file example earlier. This type stores session state in a database.

Session data must be serializable. If you attempt to store something in session state that is not serializable, you will receive the following error:

Unable to serialize the session state. In 'StateServer' and 'SQLServer' mode, ASP.NET will serialize the session state objects, and as a result non-serializable objects or MarshalByRef objects are not permitted. the same restriction applies if similar serialization is done by the custom session state store in 'Custom' mode.

There are two ways to resolve this issue: by marking the type as serializable or by using a surrogate serializer.

Marking Types as Serializable

If you have access to the source code for the type that is being stored in session state, you can mark the type using the Serializable attribute, as in the following example. If the type contains additional classes, all the contained classes must be serializable as well.

[Serializable]

public class Address { }

[Serializable]

public class Person { 

     public Address Work;

     public Address Home; 

}

Using a Surrogate Serializer in .NET Framework 4.5

If it's not practical to mark the type as serializable in source code, and if you are using .NET Framework 4.5, you can use a surrogate serializer. (This technique does not work in .NET Framework 4.)

Create a class that implements the ISerializationSurrogate interface.  In this class, you implement GetObjectData and SetObjectData methods in order to serialize and deserialze the data, respectively. In GetObjectData you invoke SerializationInfo.AddValue (using the appropriate overload for the data type of your data) to add individual fields of the object to serialize to a SerializationInfo object. In SetObjectData you extract the serialized version back to its original value in the object. Here's an example:

public class EmployeeSerializationSurrogate : ISerializationSurrogate

{

    // Serialize the Employee object to save the object name and address fields.

    public void GetObjectData(Object obj, SerializationInfo info, StreamingContext context)

    {

        Employee emp = (Employee)obj;

        info.AddValue("name", emp.name);

        info.AddValue("address", emp.address);

    }

    // Deserialize the Employee object to set the object name and address fields.

    public Object SetObjectData(Object obj, SerializationInfo info, StreamingContext context,

        ISurrogateSelector selector)

    {

        Employee emp = (Employee)obj;

        emp.name = info.GetString("name");

        emp.address = info.GetString("address");

        return null;

    }

}

You then register the serializer and the class to be serialized using the SurrogateSelector class in code, like this:

protected void Page_Load(object sender, EventArgs e)

{

    SurrogateSelector ss = new SurrogateSelector();

    ss.AddSurrogate(typeof(Employee), new StreamingContext(StreamingContextStates.All), new EmployeeSerializationSurrogate());

    SessionStateUtility.SerializationSurrogateSelector = ss;

}

Deploying to a Cloud Environment

If you are deploying to a cloud environment that has multiple web server instances, you should change session state mode from "InProc" to "Custom".  In addition, change the connection string named "DefaultConnection" to connect to an instance of SQL Server (including SQL Azure and SQL  Compact) instead of to SQL Server Express.

Known Issues

·         During the installation process, NuGet performs an exact match on items in the web.config file. If you have customized any of the elements in web.config that are updated by the installation process for ASP.NET Universal Providers, the installation process will not find these elements. Instead of updating the elements, the installation process will assume that they do not exist and add them. As a result, the web.config will effectively contain duplicate elements.

If your application is experiencing issues that indicate problems in the web.config file, make sure that the file contains the elements that are illustrated earlier in this document and remove any duplicate elements.

·         If you are working in Visual Studio and use Server Explorer to open the database that contains the membership, role, profile, or session provider tables, and if you then try to run the application, you might see an error like the following:

Cannot open database "aspnet" requested by the login. The login failed. Login failed for user 'yourname.'

To resolve this issue, right-click the database in Server Explorer and then click Close Connection.

·         The new providers do not use the same tables, stored procedures, and database objects as the SQL-based providers. If you switch to the new providers in an existing application, the data from the existing tables will not be available. We are considering creating a conversion utility to help you move existing applications to the new providers.

·         Web Parts personalization will not work with Universal Providers. You must use the SQL Personalization provider. That in turn does not work with LocalDB, so you must use SQL Server Express.

·         This release requires that the ASP.NET application be running under full trust.

Additional Resources

·         Managing Users by Using Membership

·         Managing Authorization Using Roles

·         ASP.NET Profile Providers

·         Microsoft SQL Azure

·         Microsoft SQL Server Compact

·         Configuration File and Source Code Transformations

Disclaimer

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

© 2011 Microsoft Corporation. All rights reserved.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.